<!DOCTYPE html>
<html>

<head>
  <title>Quarkus - Using OpenAPI and Swagger UI</title>
  <script id="adobe_dtm" src="https://www.redhat.com/dtm.js" type="text/javascript"></script>
  <script src="/assets/javascript/highlight.pack.js" type="text/javascript"></script>
  <META HTTP-EQUIV='Content-Security-Policy' CONTENT="default-src 'none'; script-src 'self' 'unsafe-eval' 'sha256-ANpuoVzuSex6VhqpYgsG25OHWVA1I+F6aGU04LoI+5s=' 'sha256-ipy9P/3rZZW06mTLAR0EnXvxSNcnfSDPLDuh3kzbB1w=' js.bizographics.com https://www.redhat.com assets.adobedtm.com jsonip.com https://ajax.googleapis.com https://www.googletagmanager.com https://www.google-analytics.com https://use.fontawesome.com; style-src 'self' https://fonts.googleapis.com https://use.fontawesome.com; img-src 'self' *; media-src 'self' ; frame-src https://www.googletagmanager.com https://www.youtube.com; frame-ancestors 'none'; base-uri 'none'; object-src 'none'; form-action 'none'; font-src 'self' https://use.fontawesome.com https://fonts.gstatic.com;">
  <META HTTP-EQUIV='X-Frame-Options' CONTENT="DENY">
  <META HTTP-EQUIV='X-XSS-Protection' CONTENT="1; mode=block">
  <META HTTP-EQUIV='X-Content-Type-Options' CONTENT="nosniff">
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <meta name="description" content="Quarkus: Supersonic Subatomic Java">
  <meta name="twitter:card" content="summary_large_image">
  <meta name="twitter:site" content="@QuarkusIO"> 
  <meta name="twitter:creator" content="@QuarkusIO">
  <meta property="og:url" content="https://quarkus.io/guides/openapi-swaggerui" />
  <meta property="og:title" content="Quarkus - Using OpenAPI and Swagger UI" />
  <meta property="og:description" content="Quarkus: Supersonic Subatomic Java" />
  <meta property="og:image" content="/assets/images/quarkus_card.png" />
  <link rel="canonical" href="https://quarkus.io/guides/openapi-swaggerui">
  <link rel="shortcut icon" type="image/png" href="/favicon.ico" >
  <link rel="stylesheet" href="https://quarkus.io/guides/stylesheet/config.css" />
  <link rel="stylesheet" href="/assets/css/main.css" />
  <link rel="stylesheet" href="https://use.fontawesome.com/releases/v5.1.0/css/all.css" integrity="sha384-lKuwvrZot6UHsBSfcMvOkWwlCMgc0TaWr+30HWe3a4ltaBwTZhyTEggF5tJv8tbt" crossorigin="anonymous">
  <link rel="alternate" type="application/rss+xml"  href="https://quarkus.io/feed.xml" title="Quarkus">
  <script src="https://quarkus.io/assets/javascript/goan.js" type="text/javascript"></script>
  <script src="https://quarkus.io/assets/javascript/hl.js" type="text/javascript"></script>
</head>

<body class="guides">
  <!-- Google Tag Manager (noscript) -->
  <noscript><iframe src="https://www.googletagmanager.com/ns.html?id=GTM-NJWS5L"
  height="0" width="0" style="display:none;visibility:hidden"></iframe></noscript>
  <!-- End Google Tag Manager (noscript) -->

  <div class="nav-wrapper">
  <div class="grid-wrapper">
    <div class="width-12-12">
      <input type="checkbox" id="checkbox" />
      <nav id="main-nav" class="main-nav">
  <div class="container">
    <div class="logo-wrapper">
      
        <a href="/"><img src="/assets/images/quarkus_logo_horizontal_rgb_600px_reverse.png" class="project-logo" title="Quarkus"></a>
      
    </div>
    <label class="nav-toggle" for="checkbox">
      <i class="fa fa-bars"></i>
    </label>
    <div id="menu" class="menu">
      <span>
        <a href="/get-started/" class="">Get Started</a>
      </span>
      <span>
        <a href="/guides/" class="active">Guides</a>
      </span>
      <span>
        <a href="/community/" class="">Community</a>
      </span>
      <span>
        <a href="/support/" class="">Support</a>
      </span>
      <span>
        <a href="/blog/" class="">Blog</a>
      </span>
      <span>
        <a href="https://code.quarkus.io" class="button-cta secondary white">Start Coding</a>
      </span>
    </div>
  </div>
      </nav>
    </div>
  </div>
</div>

  <div class="content">
    <div class="guide">
  <div class="width-12-12">
    <h1 class="text-caps">Quarkus - Using OpenAPI and Swagger UI</h1>
    <div class="hide-mobile toc"><ul class="sectlevel1">
<li><a href="#prerequisites">Prerequisites</a></li>
<li><a href="#architecture">Architecture</a></li>
<li><a href="#solution">Solution</a></li>
<li><a href="#creating-the-maven-project">Creating the Maven project</a></li>
<li><a href="#expose-a-rest-resource">Expose a REST Resource</a></li>
<li><a href="#expose-openapi-specifications">Expose OpenAPI Specifications</a></li>
<li><a href="#providing-application-level-openapi-annotations">Providing Application Level OpenAPI Annotations</a></li>
<li><a href="#loading-openapi-schema-from-static-files">Loading OpenAPI Schema From Static Files</a></li>
<li><a href="#changing-the-openapi-version">Changing the OpenAPI version</a></li>
<li><a href="#auto-generation-of-operation-id">Auto-generation of Operation Id</a></li>
<li><a href="#use-swagger-ui-for-development">Use Swagger UI for development</a></li>
<li><a href="#configuration-reference">Configuration Reference</a>
<ul class="sectlevel2">
<li><a href="#openapi">OpenAPI</a></li>
<li><a href="#swagger-ui">Swagger UI</a></li>
</ul>
</li>
</ul></div>
    <div>
      <div id="preamble">
<div class="sectionbody">
<div class="paragraph">
<p>This guide explains how your Quarkus application can expose its API description through an OpenAPI specification and
how you can test it via a user-friendly UI named Swagger UI.</p>
</div>
</div>
</div>
<div class="sect1">
<h2 id="prerequisites"><a class="anchor" href="#prerequisites"></a>Prerequisites</h2>
<div class="sectionbody">
<div class="paragraph">
<p>To complete this guide, you need:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>less than 15 minutes</p>
</li>
<li>
<p>an IDE</p>
</li>
<li>
<p>JDK 1.8+ installed with <code>JAVA_HOME</code> configured appropriately</p>
</li>
<li>
<p>Apache Maven 3.6.2+</p>
</li>
</ul>
</div>
</div>
</div>
<div class="sect1">
<h2 id="architecture"><a class="anchor" href="#architecture"></a>Architecture</h2>
<div class="sectionbody">
<div class="paragraph">
<p>In this guide, we create a straightforward REST application to demonstrate how fast you can expose your API
specification and benefit from a user interface to test it.</p>
</div>
</div>
</div>
<div class="sect1">
<h2 id="solution"><a class="anchor" href="#solution"></a>Solution</h2>
<div class="sectionbody">
<div class="paragraph">
<p>We recommend that you follow the instructions in the next sections and create the application step by step.
However, you can skip right to the completed example.</p>
</div>
<div class="paragraph">
<p>Clone the Git repository: <code>git clone <a href="https://github.com/quarkusio/quarkus-quickstarts.git" class="bare">https://github.com/quarkusio/quarkus-quickstarts.git</a></code>, or download an <a href="https://github.com/quarkusio/quarkus-quickstarts/archive/master.zip">archive</a>.</p>
</div>
<div class="paragraph">
<p>The solution is located in the <code>openapi-swaggerui-quickstart</code> <a href="https://github.com/quarkusio/quarkus-quickstarts/tree/master/openapi-swaggerui-quickstart">directory</a>.</p>
</div>
</div>
</div>
<div class="sect1">
<h2 id="creating-the-maven-project"><a class="anchor" href="#creating-the-maven-project"></a>Creating the Maven project</h2>
<div class="sectionbody">
<div class="paragraph">
<p>First, we need a new project. Create a new project with the following command:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-none hljs">mvn io.quarkus:quarkus-maven-plugin:1.7.0.Final:create \
    -DprojectGroupId=org.acme \
    -DprojectArtifactId=openapi-swaggerui-quickstart \
    -DclassName="org.acme.openapi.swaggerui.FruitResource" \
    -Dpath="/fruits" \
    -Dextensions="resteasy-jsonb"
cd openapi-swaggerui-quickstart</code></pre>
</div>
</div>
<div class="paragraph">
<p>This command generates the Maven project with a <code>/fruits</code> REST endpoint.</p>
</div>
</div>
</div>
<div class="sect1">
<h2 id="expose-a-rest-resource"><a class="anchor" href="#expose-a-rest-resource"></a>Expose a REST Resource</h2>
<div class="sectionbody">
<div class="paragraph">
<p>We will create a <code>Fruit</code> bean and a <code>FruitResouce</code> REST resource
(feel free to take a look to the <a href="rest-json">Writing JSON REST services guide</a> if your want more details on how to build a REST API with Quarkus).</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code data-lang="java" class="language-java hljs">package org.acme.openapi.swaggerui;

public class Fruit {

    public String name;
    public String description;

    public Fruit() {
    }

    public Fruit(String name, String description) {
        this.name = name;
        this.description = description;
    }
}</code></pre>
</div>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code data-lang="java" class="language-java hljs">package org.acme.openapi.swaggerui;

import javax.ws.rs.GET;
import javax.ws.rs.POST;
import javax.ws.rs.DELETE;
import javax.ws.rs.Path;
import javax.ws.rs.Produces;
import javax.ws.rs.Consumes;
import javax.ws.rs.core.MediaType;
import java.util.Collections;
import java.util.LinkedHashMap;
import java.util.Set;

@Path("/fruits")
@Produces(MediaType.APPLICATION_JSON)
@Consumes(MediaType.APPLICATION_JSON)
public class FruitResource {

    private Set&lt;Fruit&gt; fruits = Collections.newSetFromMap(Collections.synchronizedMap(new LinkedHashMap&lt;&gt;()));

    public FruitResource() {
        fruits.add(new Fruit("Apple", "Winter fruit"));
        fruits.add(new Fruit("Pineapple", "Tropical fruit"));
    }

    @GET
    public Set&lt;Fruit&gt; list() {
        return fruits;
    }

    @POST
    public Set&lt;Fruit&gt; add(Fruit fruit) {
        fruits.add(fruit);
        return fruits;
    }

    @DELETE
    public Set&lt;Fruit&gt; delete(Fruit fruit) {
        fruits.removeIf(existingFruit -&gt; existingFruit.name.contentEquals(fruit.name));
        return fruits;
    }
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>As we changed the API, we also need to update the test:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code data-lang="java" class="language-java hljs">package org.acme.openapi.swaggerui;

import io.quarkus.test.junit.QuarkusTest;
import org.junit.jupiter.api.Test;

import javax.ws.rs.core.MediaType;

import static io.restassured.RestAssured.given;
import static org.hamcrest.CoreMatchers.is;
import static org.hamcrest.Matchers.containsInAnyOrder;

@QuarkusTest
public class FruitResourceTest {

    @Test
    public void testList() {
        given()
                .when().get("/fruits")
                .then()
                .statusCode(200)
                .body("$.size()", is(2),
                        "name", containsInAnyOrder("Apple", "Pineapple"),
                        "description", containsInAnyOrder("Winter fruit", "Tropical fruit"));
    }

    @Test
    public void testAdd() {
        given()
                .body("{\"name\": \"Pear\", \"description\": \"Winter fruit\"}")
                .header("Content-Type", MediaType.APPLICATION_JSON)
                .when()
                .post("/fruits")
                .then()
                .statusCode(200)
                .body("$.size()", is(3),
                        "name", containsInAnyOrder("Apple", "Pineapple", "Pear"),
                        "description", containsInAnyOrder("Winter fruit", "Tropical fruit", "Winter fruit"));

        given()
                .body("{\"name\": \"Pear\", \"description\": \"Winter fruit\"}")
                .header("Content-Type", MediaType.APPLICATION_JSON)
                .when()
                .delete("/fruits")
                .then()
                .statusCode(200)
                .body("$.size()", is(2),
                        "name", containsInAnyOrder("Apple", "Pineapple"),
                        "description", containsInAnyOrder("Winter fruit", "Tropical fruit"));
    }
}</code></pre>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="expose-openapi-specifications"><a class="anchor" href="#expose-openapi-specifications"></a>Expose OpenAPI Specifications</h2>
<div class="sectionbody">
<div class="paragraph">
<p>Quarkus proposes a <code>smallrye-openapi</code> extension compliant with the <a href="https://github.com/eclipse/microprofile-open-api/">Eclipse MicroProfile OpenAPI</a>
specification in order to generate your API <a href="https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md">OpenAPI v3 specification</a>.</p>
</div>
<div class="paragraph">
<p>You just need to add the <code>openapi</code> extension to your Quarkus application:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code data-lang="shell" class="language-shell hljs">./mvnw quarkus:add-extension -Dextensions="quarkus-smallrye-openapi"</code></pre>
</div>
</div>
<div class="paragraph">
<p>This will add the following to your <code>pom.xml</code>:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code data-lang="xml" class="language-xml hljs">&lt;dependency&gt;
    &lt;groupId&gt;io.quarkus&lt;/groupId&gt;
    &lt;artifactId&gt;quarkus-smallrye-openapi&lt;/artifactId&gt;
&lt;/dependency&gt;</code></pre>
</div>
</div>
<div class="paragraph">
<p>Now, we are ready to run our application:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code data-lang="shell" class="language-shell hljs">./mvnw compile quarkus:dev</code></pre>
</div>
</div>
<div class="paragraph">
<p>Once your application is started, you can make a request to the default <code>/openapi</code> endpoint:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code data-lang="shell" class="language-shell hljs">$ curl http://localhost:8080/openapi
openapi: 3.0.3
info:
  title: Generated API
  version: "1.0"
paths:
  /fruits:
    get:
      responses:
        200:
          description: OK
          content:
            application/json: {}
    post:
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Fruit'
      responses:
        200:
          description: OK
          content:
            application/json: {}
    delete:
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Fruit'
      responses:
        200:
          description: OK
          content:
            application/json: {}
components:
  schemas:
    Fruit:
      properties:
        description:
          type: string
        name:
          type: string</code></pre>
</div>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
<div class="paragraph">
<p>If you do not like the default endpoint location <code>/openapi</code>, you can change it by adding the following configuration to your <code>application.properties</code>:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code data-lang="properties" class="language-properties hljs">quarkus.smallrye-openapi.path=/swagger</code></pre>
</div>
</div>
</td>
</tr>
</table>
</div>
<div class="paragraph">
<p>Hit <code>CTRL+C</code> to stop the application.</p>
</div>
</div>
</div>
<div class="sect1">
<h2 id="providing-application-level-openapi-annotations"><a class="anchor" href="#providing-application-level-openapi-annotations"></a>Providing Application Level OpenAPI Annotations</h2>
<div class="sectionbody">
<div class="paragraph">
<p>There are some MicroProfile OpenAPI annotations which describe global API information, such as the following:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>API Title</p>
</li>
<li>
<p>API Description</p>
</li>
<li>
<p>Version</p>
</li>
<li>
<p>Contact Information</p>
</li>
<li>
<p>License</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>All of this information (and more) can be included in your Java code by using appropriate OpenAPI annotations
on a JAX-RS <code>Application</code> class.  Because a JAX-RS <code>Application</code> class is not required in Quarkus, you will
likely have to create one.  It can simply be an empty class that extends <code>javax.ws.rs.core.Application</code>.  This
empty class can then be annotated with various OpenAPI annotations such as <code>@OpenAPIDefinition</code>.  For example:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code data-lang="java" class="language-java hljs">@OpenAPIDefinition(
    tags = {
            @Tag(name="widget", description="Widget operations."),
            @Tag(name="gasket", description="Operations related to gaskets")
    },
    info = @Info(
        title="Example API",
        version = "1.0.1",
        contact = @Contact(
            name = "Example API Support",
            url = "http://exampleurl.com/contact",
            email = "techsupport@example.com"),
        license = @License(
            name = "Apache 2.0",
            url = "http://www.apache.org/licenses/LICENSE-2.0.html"))
)
public class ExampleApiApplication extends Application {
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>Another option, that is a feature provided by SmallRye and not part of the specification, is to use configuration to add this global API information.
This way, you do not need to have a JAX-RS <code>Application</code> class, and you can name the API differently per environment.</p>
</div>
<div class="paragraph">
<p>For example, add the following to your <code>application.properties</code>:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code data-lang="properties" class="language-properties hljs">mp.openapi.extensions.smallrye.info.title=Example API
%dev.mp.openapi.extensions.smallrye.info.title=Example API (development)
%test.mp.openapi.extensions.smallrye.info.title=Example API (test)
mp.openapi.extensions.smallrye.info.version=1.0.1
mp.openapi.extensions.smallrye.info.description=Just an example service
mp.openapi.extensions.smallrye.info.termsOfService=Your terms here
mp.openapi.extensions.smallrye.info.contact.email=techsupport@example.com
mp.openapi.extensions.smallrye.info.contact.name=Example API Support
mp.openapi.extensions.smallrye.info.contact.url=http://exampleurl.com/contact
mp.openapi.extensions.smallrye.info.license.name=Apache 2.0
mp.openapi.extensions.smallrye.info.license.url=http://www.apache.org/licenses/LICENSE-2.0.html</code></pre>
</div>
</div>
<div class="paragraph">
<p>This will give you similar information as the <code>@OpenAPIDefinition</code> example above.</p>
</div>
</div>
</div>
<div class="sect1">
<h2 id="loading-openapi-schema-from-static-files"><a class="anchor" href="#loading-openapi-schema-from-static-files"></a>Loading OpenAPI Schema From Static Files</h2>
<div class="sectionbody">
<div class="paragraph">
<p>Instead of dynamically creating OpenAPI schemas from annotation scanning, Quarkus also supports serving static OpenAPI documents.
The static file to serve must be a valid document conforming to the <a href="https://swagger.io/docs/specification">OpenAPI specification</a>.
An OpenAPI document that conforms to the  OpenAPI Specification is itself a valid JSON object, that can be represented in <code>yaml</code> or <code>json</code> formats.</p>
</div>
<div class="paragraph">
<p>To see this in action, we&#8217;ll put OpenAPI documentation under <code>META-INF/openapi.yaml</code> for our <code>/fruits</code> endpoints.
Quarkus also supports alternative <a href="#open-document-paths">OpenAPI document paths</a> if you prefer.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code data-lang="shell" class="language-shell hljs">openapi: 3.0.1
info:
  title: Static OpenAPI document of fruits resource
  description: Fruit resources Open API documentation
  version: "1.0"

servers:
  - url: http://localhost:8080/openapi
    description: Optional dev mode server description

paths:
  /fruits:
    get:
      responses:
        200:
          description: OK - fruits list
          content:
            application/json: {}
    post:
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Fruit'
      responses:
        200:
          description: new fruit resource created
          content:
            application/json: {}
    delete:
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Fruit'
      responses:
        200:
          description: OK - fruit resource deleted
          content:
            application/json: {}
components:
  schemas:
    Fruit:
      properties:
        description:
          type: string
        name:
          type: string</code></pre>
</div>
</div>
<div class="paragraph">
<p>By default, a request to <code>/openapi</code> will serve the combined OpenAPI document from the static file and the model generated from application endpoints code.
We can however change this to only serve the static OpenAPI document by adding <code>mp.openapi.scan.disable=true</code> configuration into <code>application.properties</code>.</p>
</div>
<div class="paragraph">
<p>Now, a request to <code>/openapi</code> endpoint will serve the static OpenAPI document instead of the generated one.</p>
</div>
<div id="open-document-paths" class="admonitionblock tip">
<table>
<tr>
<td class="icon">
<i class="fa icon-tip" title="Tip"></i>
</td>
<td class="content">
<div class="title">About OpenAPI document paths</div>
<div class="paragraph">
<p>Quarkus supports various paths to store your OpenAPI document under. We recommend you place it under <code>META-INF/openapi.yml</code>.
Alternative paths are:</p>
</div>
<div class="ulist">
<ul>
<li>
<p><code>META-INF/openapi.yaml</code></p>
</li>
<li>
<p><code>META-INF/openapi.yml</code></p>
</li>
<li>
<p><code>META-INF/openapi.json</code></p>
</li>
<li>
<p><code>WEB-INF/classes/META-INF/openapi.yml</code></p>
</li>
<li>
<p><code>WEB-INF/classes/META-INF/openapi.yaml</code></p>
</li>
<li>
<p><code>WEB-INF/classes/META-INF/openapi.json</code></p>
</li>
</ul>
</div>
<div class="paragraph">
<p>Live reload of static OpenAPI document is supported during development. A modification to your OpenAPI document will be picked up on fly by Quarkus.</p>
</div>
</td>
</tr>
</table>
</div>
</div>
</div>
<div class="sect1">
<h2 id="changing-the-openapi-version"><a class="anchor" href="#changing-the-openapi-version"></a>Changing the OpenAPI version</h2>
<div class="sectionbody">
<div class="paragraph">
<p>By default, when the document is generated, the OpenAPI version used will be <code>3.0.3</code>. If you use a static file as mentioned above, the version in the file
will be used. You can also define the version in SmallRye using the following configuration:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code data-lang="properties" class="language-properties hljs">mp.openapi.extensions.smallrye.openapi=3.0.2</code></pre>
</div>
</div>
<div class="paragraph">
<p>This might be useful if your API go through a Gateway that needs a certain version.</p>
</div>
</div>
</div>
<div class="sect1">
<h2 id="auto-generation-of-operation-id"><a class="anchor" href="#auto-generation-of-operation-id"></a>Auto-generation of Operation Id</h2>
<div class="sectionbody">
<div class="paragraph">
<p>The <a href="https://swagger.io/docs/specification/paths-and-operations/">Operation Id</a> can be set using the <code>@Operation</code> annotation, and is in many cases useful when using a tool to generate a client stub from the schema.
The Operation Id is typically used for the method name in the client stub. In SmallRye, you can auto-generate this Operation Id by using the following configuration:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code data-lang="properties" class="language-properties hljs">mp.openapi.extensions.smallrye.operationIdStrategy=METHOD</code></pre>
</div>
</div>
<div class="paragraph">
<p>Now you do not need to use the <code>@Operation</code> annotation. While generating the document, the method name will be used for the Operation Id.</p>
</div>
<table class="tableblock frame-all grid-all stretch">
<caption class="title">Table 1. The strategies available for generating the Operation Id</caption>
<colgroup>
<col style="width: 50%;">
<col style="width: 50%;">
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top">Property value</th>
<th class="tableblock halign-left valign-top">Description</th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>METHOD</code></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Use the method name.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>CLASS_METHOD</code></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Use the class name (without the package) plus the method.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>PACKAGE_CLASS_METHOD</code></p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Use the class name plus the method name.</p></td>
</tr>
</tbody>
</table>
</div>
</div>
<div class="sect1">
<h2 id="use-swagger-ui-for-development"><a class="anchor" href="#use-swagger-ui-for-development"></a>Use Swagger UI for development</h2>
<div class="sectionbody">
<div class="paragraph">
<p>When building APIs, developers want to test them quickly. <a href="https://swagger.io/tools/swagger-ui/">Swagger UI</a> is a great tool
permitting to visualize and interact with your APIs.
The UI is automatically generated from your OpenAPI specification.</p>
</div>
<div class="paragraph">
<p>The Quarkus <code>smallrye-openapi</code> extension comes with a <code>swagger-ui</code> extension embedding a properly configured Swagger UI page.</p>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
<div class="paragraph">
<p>By default, Swagger UI is only available when Quarkus is started in dev or test mode.</p>
</div>
<div class="paragraph">
<p>If you want to make it available in production too, you can include the following configuration in your <code>application.properties</code>:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code data-lang="properties" class="language-properties hljs">quarkus.swagger-ui.always-include=true</code></pre>
</div>
</div>
<div class="paragraph">
<p>This is a build time property, it cannot be changed at runtime after your application is built.</p>
</div>
</td>
</tr>
</table>
</div>
<div class="paragraph">
<p>By default, Swagger UI is accessible at <code>/swagger-ui</code>.</p>
</div>
<div class="paragraph">
<p>You can update this path by setting the <code>quarkus.swagger-ui.path</code> property in your <code>application.properties</code>:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code data-lang="properties" class="language-properties hljs">quarkus.swagger-ui.path=/my-custom-path</code></pre>
</div>
</div>
<div class="admonitionblock warning">
<table>
<tr>
<td class="icon">
<i class="fa icon-warning" title="Warning"></i>
</td>
<td class="content">
<div class="paragraph">
<p>The value <code>/</code> is not allowed as it blocks the application from serving anything else.</p>
</div>
</td>
</tr>
</table>
</div>
<div class="paragraph">
<p>Now, we are ready to run our application:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code data-lang="shell" class="language-shell hljs">./mvnw compile quarkus:dev</code></pre>
</div>
</div>
<div class="paragraph">
<p>You can check the Swagger UI path in your application&#8217;s log:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlightjs highlight"><code class="language-none hljs">00:00:00,000 INFO  [io.qua.swa.run.SwaggerUiServletExtension] Swagger UI available at /swagger-ui</code></pre>
</div>
</div>
<div class="paragraph">
<p>Once your application is started, you can go to <a href="http://localhost:8080/swagger-ui" class="bare">http://localhost:8080/swagger-ui</a> and play with your API.</p>
</div>
<div class="paragraph">
<p>You can visualize your API&#8217;s operations and schemas.
<span class="image"><img src="/guides/images/openapi-swaggerui-guide-screenshot01.png" alt="Visualize your API"></span></p>
</div>
<div class="paragraph">
<p>You can also interact with your API in order to quickly test it.
<span class="image"><img src="/guides/images/openapi-swaggerui-guide-screenshot02.png" alt="Interact with your API"></span></p>
</div>
<div class="paragraph">
<p>Hit <code>CTRL+C</code> to stop the application.</p>
</div>
</div>
</div>
<div class="sect1">
<h2 id="configuration-reference"><a class="anchor" href="#configuration-reference"></a>Configuration Reference</h2>
<div class="sectionbody">
<div class="sect2">
<h3 id="openapi"><a class="anchor" href="#openapi"></a>OpenAPI</h3>
<div class="paragraph configuration-legend">
<p><span class="icon"><i class="fa fa-lock" title="Fixed at build time"></i></span> Configuration property fixed at build time - All other configuration properties are overridable at runtime</p>
</div>
<table class="tableblock frame-all grid-all stretch configuration-reference searchable">
<colgroup>
<col style="width: 80%;">
<col style="width: 10%;">
<col style="width: 10%;">
</colgroup>
<tbody>
<tr>
<th class="tableblock halign-left valign-top"><p class="tableblock"><a id="quarkus-smallrye-openapi_configuration"></a><a href="#quarkus-smallrye-openapi_configuration">Configuration property</a></p></th>
<th class="tableblock halign-left valign-middle"><p class="tableblock">Type</p></th>
<th class="tableblock halign-left valign-middle"><p class="tableblock">Default</p></th>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><span class="icon"><i class="fa fa-lock" title="Fixed at build time"></i></span> <a id="quarkus-smallrye-openapi_quarkus.smallrye-openapi.path"></a><code><a href="#quarkus-smallrye-openapi_quarkus.smallrye-openapi.path">quarkus.smallrye-openapi.path</a></code></p>
</div>
<div class="openblock description">
<div class="content">
<div class="paragraph">
<p>The path at which to register the OpenAPI Servlet.</p>
</div>
</div>
</div></div></td>
<td class="tableblock halign-left valign-middle"><p class="tableblock">string</p></td>
<td class="tableblock halign-left valign-middle"><p class="tableblock"><code>/openapi</code></p></td>
</tr>
</tbody>
</table>
</div>
<div class="sect2">
<h3 id="swagger-ui"><a class="anchor" href="#swagger-ui"></a>Swagger UI</h3>
<div class="paragraph configuration-legend">
<p><span class="icon"><i class="fa fa-lock" title="Fixed at build time"></i></span> Configuration property fixed at build time - All other configuration properties are overridable at runtime</p>
</div>
<table class="tableblock frame-all grid-all stretch configuration-reference searchable">
<colgroup>
<col style="width: 80%;">
<col style="width: 10%;">
<col style="width: 10%;">
</colgroup>
<tbody>
<tr>
<th class="tableblock halign-left valign-top"><p class="tableblock"><a id="quarkus-swaggerui_configuration"></a><a href="#quarkus-swaggerui_configuration">Configuration property</a></p></th>
<th class="tableblock halign-left valign-middle"><p class="tableblock">Type</p></th>
<th class="tableblock halign-left valign-middle"><p class="tableblock">Default</p></th>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><span class="icon"><i class="fa fa-lock" title="Fixed at build time"></i></span> <a id="quarkus-swaggerui_quarkus.swagger-ui.path"></a><code><a href="#quarkus-swaggerui_quarkus.swagger-ui.path">quarkus.swagger-ui.path</a></code></p>
</div>
<div class="openblock description">
<div class="content">
<div class="paragraph">
<p>The path where Swagger UI is available.
 The value <code>/</code> is not allowed as it blocks the application from serving anything else.</p>
</div>
</div>
</div></div></td>
<td class="tableblock halign-left valign-middle"><p class="tableblock">string</p></td>
<td class="tableblock halign-left valign-middle"><p class="tableblock"><code>/swagger-ui</code></p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><span class="icon"><i class="fa fa-lock" title="Fixed at build time"></i></span> <a id="quarkus-swaggerui_quarkus.swagger-ui.always-include"></a><code><a href="#quarkus-swaggerui_quarkus.swagger-ui.always-include">quarkus.swagger-ui.always-include</a></code></p>
</div>
<div class="openblock description">
<div class="content">
<div class="paragraph">
<p>If this should be included every time. By default this is only included when the application is running in dev mode.</p>
</div>
</div>
</div></div></td>
<td class="tableblock halign-left valign-middle"><p class="tableblock">boolean</p></td>
<td class="tableblock halign-left valign-middle"><p class="tableblock"><code>false</code></p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><div class="content"><div class="paragraph">
<p><span class="icon"><i class="fa fa-lock" title="Fixed at build time"></i></span> <a id="quarkus-swaggerui_quarkus.swagger-ui.enable"></a><code><a href="#quarkus-swaggerui_quarkus.swagger-ui.enable">quarkus.swagger-ui.enable</a></code></p>
</div>
<div class="openblock description">
<div class="content">
<div class="paragraph">
<p>If Swagger UI should be enabled. By default, Swagger UI is enabled.</p>
</div>
</div>
</div></div></td>
<td class="tableblock halign-left valign-middle"><p class="tableblock">boolean</p></td>
<td class="tableblock halign-left valign-middle"><p class="tableblock"><code>true</code></p></td>
</tr>
</tbody>
</table>
</div>
</div>
</div>
    </div>
  </div>
</div>

  </div>

  <div class="content project-footer">
  <div class="footer-section">
    <div class="logo-wrapper">
      <a href="/"><img src="/assets/images/quarkus_logo_horizontal_rgb_reverse.svg" class="project-logo" title="Quarkus"></a>
    </div>
  </div>
  <div class="grid-wrapper">
    <p class="grid__item width-3-12">Quarkus is open. All dependencies of this project are available under the <a href='https://www.apache.org/licenses/LICENSE-2.0' target='_blank'>Apache Software License 2.0</a> or compatible license.<br /><br />This website was built with <a href='https://jekyllrb.com/' target='_blank'>Jekyll</a>, is hosted on <a href='https://pages.github.com/' target='_blank'>Github Pages</a> and is completely open source. If you want to make it better, <a href='https://github.com/quarkusio/quarkusio.github.io' target='_blank'>fork the website</a> and show us what you’ve got.</p>

    
      <div class="width-1-12 project-links">
        <span>Navigation</span>
        <ul class="footer-links width-1-12">
          
            <li><a href="/">Home</a></li>
          
            <li><a href="/guides">Guides</a></li>
          
            <li><a href="/community/#contributing">Contribute</a></li>
          
            <li><a href="/faq">FAQ</a></li>
          
            <li><a href="/get-started">Get Started</a></li>
          
        </ul>
      </div>
    
      <div class="width-1-12 project-links">
        <span>Contribute</span>
        <ul class="footer-links width-1-12">
          
            <li><a href="https://twitter.com/quarkusio">Follow us</a></li>
          
            <li><a href="https://github.com/quarkusio">GitHub</a></li>
          
            <li><a href="/security">Security&nbsp;policy</a></li>
          
        </ul>
      </div>
    
      <div class="width-1-12 project-links">
        <span>Get Help</span>
        <ul class="footer-links width-1-12">
          
            <li><a href="https://groups.google.com/forum/#!forum/quarkus-dev">Forums</a></li>
          
            <li><a href="https://quarkusio.zulipchat.com">Chatroom</a></li>
          
        </ul>
      </div>
    

    
      <div class="width-3-12 more-links">
        <span>Quarkus is made of community projects</span>
        <ul class="footer-links">
          
            <li><a href="https://vertx.io/" target="_blank">Eclipse Vert.x</a></li>
          
            <li><a href="https://microprofile.io" target="_blank">Eclipse MicroProfile</a></li>
          
            <li><a href="https://hibernate.org" target="_blank">Hibernate</a></li>
          
            <li><a href="https://netty.io" target="_blank">Netty</a></li>
          
            <li><a href="https://resteasy.github.io" target="_blank">RESTEasy</a></li>
          
            <li><a href="https://camel.apache.org" target="_blank">Apache Camel</a></li>
          
            <li><a href="https://code.quarkus.io/" target="_blank">And many more...</a></li>
          
        </ul>
      </div>
    
  </div>
</div>
  <div class="content redhat-footer">
  <div class="grid-wrapper">
    <span class="licence">
      <i class="fab fa-creative-commons"></i><i class="fab fa-creative-commons-by"></i> <a href="https://creativecommons.org/licenses/by/3.0/" target="_blank">CC by 3.0</a> | <a href="https://www.redhat.com/en/about/privacy-policy">Privacy Policy</a>
    </span>
    <span class="redhat">
      Sponsored by
    </span>
    <span class="redhat-logo">
      <a href="https://www.redhat.com/" target="_blank"><img src="/assets/images/redhat_reversed.svg"></a>
    </span>
  </div>
</div>


  <script src="https://ajax.googleapis.com/ajax/libs/jquery/2.1.4/jquery.min.js" integrity="sha384-8gBf6Y4YYq7Jx97PIqmTwLPin4hxIzQw5aDmUg/DDhul9fFpbbLcLh3nTIIDJKhx" crossorigin="anonymous"></script>
  <script type="text/javascript" src="/assets/javascript/mobile-nav.js"></script>
  <script type="text/javascript" src="/assets/javascript/scroll-down.js"></script>
  <script src="/assets/javascript/satellite.js" type="text/javascript"></script>
  <script src="https://quarkus.io/guides/javascript/config.js" type="text/javascript"></script>
  <script src="/assets/javascript/search-filter.js" type="text/javascript"></script>
  <script src="/assets/javascript/back-to-top.js" type="text/javascript"></script>
</body>

</html>
